Apple // Game Server
Play the classics on your Woz machine without a floppy disk!Program Overview
Prior to executing the java program, the apple // computer must be connected, powered on, and expecting input (via typing in#2 at the basic prompt.) Once you've typed IN#2, the apple SSC firmware (or equivilant firmware in the rom of the //gs or //c) takes over the normal keyboard input routine and starts listening on the serial port for input in addition to the normal keyboard input. Therefore, whatever is connected to the serial port can gain remote control over the apple's keyboard and type stuff in really fast -- well, at least fast compared to how I type anyway. ;-) So now the apple is listening for input, we can now start the java program.The first phase of the java program is contained in two script files, init.txt and driver.txt, which contain all the necessary logic for getting the apple ready for higher speed communication. Very simply, a short pre-assembled apple program (nicknamed SOS, for Serial Operating System) is typed in one byte at a time over the serial cable and then executed on the apple.
Note:
The init phase is where the bulk of problems are experienced, because
of the possibility of misconfiguration or a damaged serial cable.
Because of this, it is very important to check the link works
bi-directionally first using a normal communications program like
HyperTerminal (or whatever is relevant to your OS -- feel free to share
your opinions on this in the forums.) Whatever error messages
can be thrown by the java program are described in the FAQ section.
Once the driver program has been entered in memory, it is executed by the final line of driver.txt: "300g". Once the driver starts, the java program can gain more direct control over the apple to perform specific functions. The first thing that happens is an ackowledgement test. The java program sends an @ (at) character to the apple. The Apple, if working properly at this point, should respond with "hi". If the test succeeds, an entire application starts executing inside of the java program, using the apple as the display and keyboard input, basically turning the apple into a dumb terminal.
Main Loop: The java program prepares a virtual screen buffer in its own memory space and then sends it over (1kb total) to the apple, instructing the apple to store the data directly in its text screen buffer ($400). After the screen is sent, the java program then tells the apple to wait for a keypress. If the apple receives a keypress it sends it back. (if not, it sends back a negative response -- this is used to verify the connection is unbroken) If the keypress is understood by the java program, it responds to it and then updates its virtual screen buffer and then sends the screen back to the apple. This whole process loops until the user selects a game.
Once the game is selected, the java program sends the binary of the game file over and then instructs the driver to start executing it. After that, the java program disconnects and exits and the apple is (hopefully) now playing a game.
Script Commands
The init.txt and driver.txt files are interpreted scripts that contain all the necessary setup commands and apple program code necessary to get the apple to communicate with the java program more directly. These scripts may be found in the lib/data directory. The ags.communications.GenericHost class is where the script interpreter lives for now.The init.txt script is executed first to set up the basic parameters of the program and get the apple ready to receive the driver program code. If the init.txt script is successful, the driver.txt script is executed to enter and start the driver program.
When a script is executed, it is interpreted top-down starting at the first line. The punctuation symbols at the beginning of each line control the script flow and how data should be sent to the apple.
Script Key:
- (none) The line is typed with echo-check enabled and no prompt response expected
- ~ (tilde) The line is blindly typed (no echo-check enabled) and no prompt response expected
- * (asterisk) The line is typed with echo-check enabled and expects a monitor prompt in response
- ] (left-bracket) The line is typed with echo-check enabled and expects a basic prompt in response
- " (double-quote) The line is echoed out to the apple's screen, implicitly expects a monitor prompt afterwards
- ' (single-quote) The line is echoed out to the user (java) through stdout
- ! (exclamation) This is a command for the java program to interpret, not to be typed (see java program commands below)
- : (colon) This is a label for the java progrram, not to be typed
- ; (semi-colon) The line is a comment and is ignored
- baud rate Set the local machine's baud rate to the specified number
- flow NONE|HARDWARE|XON Set the local machine's flow control mode
- onerror label-name If an error is encountered, jump to the specified label in this script (throws the error if the label is not found)
- goto label-name Jump directly to the specified label (throws an error if the label is not found)
- wait milliseconds Pause the specified number of milliseconds before going on.
- expect true|false Enable/disable echo-check
If the echo check fails, the java program will throw an error indicating the apple is not communicating correctly. This is how baud rate detection works, because a failure of echo-checking means the baud rates don't match up. However, with echo-check mode disabled the baud rate detection will not work because there will not be a communication error until the very end once the java program has already tried to send over and execute the driver program
Serial Operating System (SOS)
SOS is the apple driver program that allows the java progam to take total control. Until SOS is instructed to execute a program, it runs its own simple main loop:- Wait for input "command" character from remote host (java program)
- Pick appropriate subroutine for command and execute it (if command was not understood, it just beeps the apple speaker)
- Unless the program execute command (E) was called, jump back to step 1.
- @ Acknowledge request -- apple responds back with "hi"
- A Set target address for execution or for data download
- B Set data download size
- C Receive n bytes of data (as set by B) and store them starting at address specified by A -- calculates checksum as it downloads
- D Request calculated checksum value (apple replies back with a one-byte checksum value, an XOR of all received bytes from C)
- E Execute program at target address specified by A
- F Wait a little while for keypress and respond back with value. (>=128 means key was pressed, < 128 means no key was pressed)